package org.or5e.api.liveradio;

import java.util.Set;

import org.or5e.api.mp.player.audio.AudioPlayer;

/**
 *  This is the primary Interface for the Live Radio. This package comes with the
 * Default Implementation too.
 *
 * @since 1.0b
 * @see org.or5e.core.api.liveradio.LiveRadioSpi
 * @author Ponraj Suthanthriamani
 */
public interface LiveRadio {

    /**
     * Initilizing the Radio Channel, this needs to have the Provider name as well
     * as the Property file which has the key value pair of the Radio provider list
     * 
     * @param radioProvider - This is the provider name currently we support shout
     * @param propFile - the property file which has the key and value of the url
     * @return true if it is success and false if not initilized properly.
     * @throws LiveRadioException
     */
    public boolean initilizeRadioChannels(String radioProvider, String propFile) throws LiveRadioException;


    /**
     * This will return the initilized channels which is available to listen. we need
     * to provide the key when we need to play this channel.
     * 
     * @return @see java.util.Set this will have the list of the Available channel to listen
     * @throws LiveRadioException
     */
    public Set<String> getAvailableChannelList() throws LiveRadioException;

    /**
     * This will start play the channel we ask for. Need to make sure you provide the
     * rite channel name so that to avoid the exceptional behaviour. you will get the
     * valid channel name using getAvailableChannelList(). if there is already a channel
     * is playing then it will stop the current playing radio and start the new one.
     * @param channelName
     * @throws LiveRadioException
     */
    public void playChannel(String channelName) throws LiveRadioException;

    /**
     * This will stop the current radio channel track.
     * @param channelName
     * @throws LiveRadioException
     */
    public void stopChannel(String channelName) throws LiveRadioException;

    /**
     * Yet to be implemented
     * @return
     * @throws LiveRadioException
     */
    public Float increaseVolume() throws LiveRadioException;

    /**
     * Yet to be implemted
     * @return
     * @throws LiveRadioException
     */
    public Float decreaseVolume() throws LiveRadioException;

    /**
     * Yet to be implemented
     * @param volumeLevel
     * @throws LiveRadioException
     */
    public void setVolume(Float volumeLevel) throws LiveRadioException;

    /**
     * This will return the Channel information like, URL, Title etc
     * @param availChannelList
     * @return
     * @throws LiveRadioException
     */
    public RadioInfo getChannelInfo(String availChannelList) throws LiveRadioException;

    /**
     * If you want to set your own Audio player configuration. you can created your
     * own audio player and configure of your own desire and set it to this component
     * @param audioPlayer
     */
    public void setAudioComponent(AudioPlayer audioPlayer);
    

    /**
     * Life cycle method which will deinitilize all the resource loced by this API.
     * @return
     * @throws LiveRadioException
     */
    public boolean destroyRadioChannels() throws LiveRadioException;
}